<%inherit file="../layout/layout.html" />
<h1>Notifry API</h1>

<p>To send messages to devices, you'll need to use the Notifry API. It's designed to be as simple as possible to send messages.</p>

<p>The API is a simple REST interface that returns JSON (at the moment). The keys below show how it is done. Alternately, 
scripts already exist to send messages to Notifry, and you can choose one that fits your platform and system.</p>

<h2>Standalone Scripts</h2>

<table class="details">
	<tr>
		<th>Language</th>
		<th>Description</th>
		<th>Link</th>
	</tr>
	<tr class="odd">
		<td>PHP</td>
		<td>A basic command line PHP script that can send messages.</td>
		<td><a href="http://notifry.googlecode.com/svn/trunk/serverpush/notifry.php">From Google Code</a></td>
	</tr>
	<tr class="even">
		<td>Python</td>
		<td>A basic command line Python script that can send messages.</td>
		<td><a href="http://notifry.googlecode.com/svn/trunk/serverpush/notifry.py">From Google Code</a></td>
	</tr>
</table>

<h2>Nagios integration</h2>

<p>If you have Nagios, you can easily integrate Notifry to send notifications.</p>

<ol>
	<li>Download one of the scripts above and put it somewhere on the server.</li>
	<li>Make sure the script is executable.</li>
	<li>Make sure the script runs - the Python script requires 2.6 or greater, and the PHP script requires 5.2 or greater (with the curl module installed).</li>
	<li>Add the following commands to your Nagios configuration, replacing the script path as appropriate. Also, you can customize the message to your liking.
	<pre class="code">
define command{
        command_name    notify-host-by-notifry
        command_line    /usr/bin/printf "%b" "Info: $HOSTOUTPUT$\n\nDate/Time: $LONGDATETIME$\n" | /etc/nagios3/notifry.py -s $CONTACTADDRESS1$ -t "$HOSTNAME$ is $HOSTSTATE$" -m -
        }

define command{
        command_name    notify-service-by-notifry
        command_line    /usr/bin/printf "%b" "Info: $SERVICEOUTPUT$\nDate/Time: $LONGDATETIME$" | /etc/nagios3/notifry.py -s "$CONTACTADDRESS1$" -t "$SERVICEDESC$ on $HOSTALIAS$ is $SERVICESTATE$" -m -
        }
	</pre>
	</li>
	<li>Modify the contacts to add the notification commands, and use address1 as the source key for that user. If you are already using address1 for something else, use another address field and change the commands above.
	<pre class="code">
define contact{
        ...
        service_notification_commands   notify-service-by-email,notify-service-by-notifry
        host_notification_commands      notify-host-by-email,notify-host-by-notifry
        ...
        address1                        aabbccddeeff00112233445566778899
        }
	</pre>
	</li>
	<li>Test your configuration.</li>
</ol>

<p>&nbsp;</p>

<h2>Zabbix Integration</h2>

<p>If you have a Zabbix server, you can send messages with the following instructions.</p>

<ol>
	<li>Set up either the PHP or Python version of the script, and test that it works. A suggestion is to
		place it into /etc/zabbix/alert.d.</li>
	<li>Add another script into /etc/zabbix/alert.d, called notifry.sh, with this as the contents. Make the script executable
		and adjust the path to the notifry program as appropriate.
		<pre class="code">
#!/bin/bash

SOURCE=$1
EVENT=$2
NOTIFICATION=$3

/etc/zabbix/alert.d/notifry.py -s "$SOURCE" -t "$EVENT" -m "$3"</pre>
	</li>
	<li>Add a new Media type to Zabbix. (Found under Administration -> Media types). Use the following settings:
		<ul>
			<li>Description: Notifry</li>
			<li>Type: script</li>
			<li>Script name: notifry.sh</li>
		</ul>
	</li>
	<li>Each user can now add a media type of Notifry to their profile. In the 'send to', use the source key.</li>
</ol>

<p>&nbsp;</p>

<h2>API Reference</h2>

<h3>Parameters</h3>

<p class="important_note"><span class="important_note_title">Note:</span> the total message shouldn't be more than around 500 bytes.
	The server will truncate your message field if it can to limit the message size. It will never truncate the URL or title.
	If it can't send the message without truncating the URL and title, the message will not be sent and you will get an error message.
	If your message is truncated, the response will have the truncated flag set to true. Notifry is not designed to send long messages.</p>

<table class="details">
	<tr>
		<th>Parameter</th>
		<th>Value</th>
		<th>Description</th>
		<th>Required</th>
	</tr>
	<tr class="odd">
		<td>format</td>
		<td>json</td>
		<td>Determines the format of the response. Only JSON is supported at the moment, so you should always send the string json.</td>
		<td>Required</td>
	</tr>
	<tr class="even">
		<td>source</td>
		<td>32 character hash string</td>
		<td>The source key, given to you by the user. They generate it when they create a source. You can supply up to 10 sources at a time separated by a comma, or a single source.</td>
		<td>Required</td>
	</tr>
	<tr class="odd">
		<td>title</td>
		<td>string</td>
		<td>The string title of this notification. Keep this short and relevant to the message.</td>
		<td>Required</td>
	</tr>
	<tr class="even">
		<td>message</td>
		<td>string</td>
		<td>The body of the message. This can contain a lot more detail of the message. This is optional, and will be sent as an empty string if not provided.</td>
		<td>Optional</td>
	</tr>
	<tr class="odd">
		<td>url</td>
		<td>string</td>
		<td>An optional URL to pass along, that would give more information about the message.</td>
		<td>Optional</td>
	</tr>
</table>

<h3>Sending the message</h3>

<p>You can POST or GET the message to:</p>

<pre class="code">https://notifrier.appspot.com/notifry</pre>

<p>If sending to a single source (or multiple sources without error), upon success, the response will look like as below:</p>

<pre class="code">{
	"messages": 1,
	"size": 68,
	"truncated": false
}</pre>

<p>If sending to multiple sources which causes some errors, the response will look like as below.
The error field indicates which sources failed and why. You can compare the number of sources
you sent with the messages field to see if all messages were sent.</p>

<pre class="code">{
	"size": 41
	"error": "46e38849bc5925945e0ae30d50bf2ea2: No source matches this key",
	"messages": 1,
	"truncated": false,
}</pre>

<p>On complete failure, the error message is returned. The hash matches your incoming source key.</p>

<pre class="code">{
	"messages": 0,
	"error": "46e38849bc5925945e0ae30d50bf2ea2: Error message describing why it failed."
}</pre>
